From d5d0cf61b98a2a3640205a114cb0666b4126ddce Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Mon, 1 Mar 2021 01:45:04 -0500 Subject: [PATCH] padcontroller: Convert docs --- gtk/gtkpadcontroller.c | 121 ++++++++++++++++++++++------------------- 1 file changed, 64 insertions(+), 57 deletions(-) diff --git a/gtk/gtkpadcontroller.c b/gtk/gtkpadcontroller.c index c4871aa981..ddee7931e6 100644 --- a/gtk/gtkpadcontroller.c +++ b/gtk/gtkpadcontroller.c @@ -18,53 +18,55 @@ */ /** - * SECTION:gtkpadcontroller - * @Short_description: Controller for drawing tablet pads - * @Title: GtkPadController - * @See_also: #GtkEventController, #GdkDevicePad + * GtkPadController: * - * #GtkPadController is an event controller for the pads found in drawing - * tablets (The collection of buttons and tactile sensors often found around - * the stylus-sensitive area). + * `GtkPadController` is an event controller for the pads found in drawing + * tablets. + * + * Pads are the collection of buttons and tactile sensors often found around + * the stylus-sensitive area. * * These buttons and sensors have no implicit meaning, and by default they - * perform no action, this event controller is provided to map those to - * #GAction objects, thus letting the application give those a more semantic - * meaning. + * perform no action. `GtkPadController` is provided to map those to + * `GAction` objects, thus letting the application give them a more + * semantic meaning. + * + * Buttons and sensors are not constrained to triggering a single action, + * some %GDK_SOURCE_TABLET_PAD devices feature multiple "modes". All these + * input elements have one current mode, which may determine the final action + * being triggered. * - * Buttons and sensors are not constrained to triggering a single action, some - * %GDK_SOURCE_TABLET_PAD devices feature multiple "modes", all these input - * elements have one current mode, which may determine the final action - * being triggered. Pad devices often divide buttons and sensors into groups, - * all elements in a group share the same current mode, but different groups - * may have different modes. See gdk_device_pad_get_n_groups() and - * gdk_device_pad_get_group_n_modes(). + * Pad devices often divide buttons and sensors into groups. All elements + * in a group share the same current mode, but different groups may have + * different modes. See [method@Gdk.DevicePad.get_n_groups] and + * [method@Gdk.DevicePad.get_group_n_modes]. * * Each of the actions that a given button/strip/ring performs for a given - * mode is defined by #GtkPadActionEntry, it contains an action name that - * will be looked up in the given #GActionGroup and activated whenever the - * specified input element and mode are triggered. + * mode is defined by a [struct@Gtk.PadActionEntry]. It contains an action + * name that will be looked up in the given `GActionGroup` and activated + * whenever the specified input element and mode are triggered. * - * A simple example of #GtkPadController usage, assigning button 1 in all + * A simple example of `GtkPadController` usage: Assigning button 1 in all * modes and pad devices to an "invert-selection" action: - * |[ - * GtkPadActionEntry *pad_actions[] = { - * { GTK_PAD_ACTION_BUTTON, 1, -1, "Invert selection", "pad-actions.invert-selection" }, - * … - * }; * + * ```c + * GtkPadActionEntry *pad_actions[] = { + * { GTK_PAD_ACTION_BUTTON, 1, -1, "Invert selection", "pad-actions.invert-selection" }, * … - * action_group = g_simple_action_group_new (); - * action = g_simple_action_new ("pad-actions.invert-selection", NULL); - * g_signal_connect (action, "activate", on_invert_selection_activated, NULL); - * g_action_map_add_action (G_ACTION_MAP (action_group), action); - * … - * pad_controller = gtk_pad_controller_new (action_group, NULL); - * ]| + * }; + * + * … + * action_group = g_simple_action_group_new (); + * action = g_simple_action_new ("pad-actions.invert-selection", NULL); + * g_signal_connect (action, "activate", on_invert_selection_activated, NULL); + * g_action_map_add_action (G_ACTION_MAP (action_group), action); + * … + * pad_controller = gtk_pad_controller_new (action_group, NULL); + * ``` * * The actions belonging to rings/strips will be activated with a parameter * of type %G_VARIANT_TYPE_DOUBLE bearing the value of the given axis, it - * is required that those are made stateful and accepting this #GVariantType. + * is required that those are made stateful and accepting this `GVariantType`. */ #include "config.h" @@ -389,24 +391,26 @@ gtk_pad_controller_init (GtkPadController *controller) /** * gtk_pad_controller_new: - * @group: #GActionGroup to trigger actions from + * @group: `GActionGroup` to trigger actions from * @pad: (nullable): A %GDK_SOURCE_TABLET_PAD device, or %NULL to handle all pads * - * Creates a new #GtkPadController that will associate events from @pad to - * actions. A %NULL pad may be provided so the controller manages all pad devices - * generically, it is discouraged to mix #GtkPadController objects with %NULL - * and non-%NULL @pad argument on the same toplevel window, as execution order - * is not guaranteed. + * Creates a new `GtkPadController` that will associate events from @pad to + * actions. + * + * A %NULL pad may be provided so the controller manages all pad devices + * generically, it is discouraged to mix `GtkPadController` objects with + * %NULL and non-%NULL @pad argument on the same toplevel window, as execution + * order is not guaranteed. * - * The #GtkPadController is created with no mapped actions. In order to map pad - * events to actions, use gtk_pad_controller_set_action_entries() or - * gtk_pad_controller_set_action(). + * The `GtkPadController` is created with no mapped actions. In order to + * map pad events to actions, use [method@Gtk.PadController.set_action_entries] + * or [method@Gtk.PadController.set_action]. * - * Be aware that pad events will only be delivered to #GtkWindows, so adding a pad - * controller to any other type of widget will not have an effect. + * Be aware that pad events will only be delivered to `GtkWindow`s, so adding + * a pad controller to any other type of widget will not have an effect. * - * Returns: A newly created #GtkPadController - **/ + * Returns: A newly created `GtkPadController` + */ GtkPadController * gtk_pad_controller_new (GActionGroup *group, GdkDevice *pad) @@ -465,13 +469,15 @@ gtk_pad_controller_add_entry (GtkPadController *controller, /** * gtk_pad_controller_set_action_entries: - * @controller: a #GtkPadController + * @controller: a `GtkPadController` * @entries: (array length=n_entries): the action entries to set on @controller * @n_entries: the number of elements in @entries * - * This is a convenience function to add a group of action entries on - * @controller. See #GtkPadActionEntry and gtk_pad_controller_set_action(). - **/ + * A convenience function to add a group of action entries on + * @controller. + * + * See [struct@Gtk.PadActionEntry] and [method@Gtk.PadController.set_action]. + */ void gtk_pad_controller_set_action_entries (GtkPadController *controller, const GtkPadActionEntry *entries, @@ -488,7 +494,7 @@ gtk_pad_controller_set_action_entries (GtkPadController *controller, /** * gtk_pad_controller_set_action: - * @controller: a #GtkPadController + * @controller: a `GtkPadController` * @type: the type of pad feature that will trigger this action * @index: the 0-indexed button/ring/strip number that will trigger this action * @mode: the mode that will trigger this action, or -1 for all modes. @@ -496,15 +502,16 @@ gtk_pad_controller_set_action_entries (GtkPadController *controller, * be deemed user-visible. * @action_name: action name that will be activated in the #GActionGroup * - * Adds an individual action to @controller. This action will only be activated - * if the given button/ring/strip number in @index is interacted while - * the current mode is @mode. -1 may be used for simple cases, so the action - * is triggered on all modes. + * Adds an individual action to @controller. + * + * This action will only be activated if the given button/ring/strip number + * in @index is interacted while the current mode is @mode. -1 may be used + * for simple cases, so the action is triggered on all modes. * * The given @label should be considered user-visible, so internationalization * rules apply. Some windowing systems may be able to use those for user * feedback. - **/ + */ void gtk_pad_controller_set_action (GtkPadController *controller, GtkPadActionType type, -- 2.30.2